- Rebalance decision matrix to ethrex vs Reth binary comparison;
  move "from scratch" and "revm only" to appendix
- Adjust Reth scores: ZK 1→2 (Zeth exists), manageability 2→3
  (modular arch acknowledged), sync 5→4 for ethrex (less battle-tested)
- Add EXIT criteria with 4 elements: metric, deadline, action, owner
- Add Tier S PoC section: perf_opcode_timings build verification
  and code path analysis
- Add JIT technical barriers (dynamic jumps, revmc reference)
- Fix weighted sum arithmetic (Reth 2.85→2.80)

Record completed work: DECISION.md creation, Volkov R6 review (6.5/10),
three mandatory fixes (matrix rebalance, EXIT criteria, Tier S PoC),
Reth/Zeth/ExEx research findings, and next steps for Phase 1.1.

- DECISION.md: DRAFT → FINAL
- Replace human staffing model with AI Agent development model
- Add bus factor policy (Kevin as interim decision-maker)
- Replace staffing risks with agent-specific risks
- Remove Senior Rust 2명 EXIT criterion
- Add 11 custom commands (.claude/commands/):
  - Development: /rust, /evm, /jit, /debugger, /l2
  - Verification: /quality-gate, /safety-review, /diff-test
  - Operations: /rebase-upstream, /phase, /bench
- Volkov R8: 7.5/10 PROCEED achieved

Architecture analysis documents:
- OVERVIEW.md: 25+2 crate dependency graph, node startup flow, CI inventory
- LEVM.md: VM struct, execution flow, dual-dispatch loop, hook system
- MODIFICATION-POINTS.md: 5 modification points, hybrid isolation strategy
- PHASE-1-1.md: Phase 1.1 execution plan with success criteria

Phase 1.1 infrastructure:
- Skeleton crates: tokamak-jit, tokamak-bench, tokamak-debugger
- Feature flag: `tokamak` propagation chain (cmd → vm → levm)
- Workspace registration for 3 new crates

- Fix OpcodeTimings: remove false min/max claim, document 4 actual fields
- Fix CallFrame: caller→msg_sender, Bytes→Code, return_data→output/sub_return_data
- Fix opcode table: describe const fn chaining pattern accurately
- Label all pseudocode snippets consistently (JIT, debugger, L2 hook)
- Plan feature flag split: tokamak → tokamak-jit/debugger/l2
- Add JIT-VM interface complexity analysis (5 challenges)
- Add failure scenarios & mitigations table (5 scenarios)
- Record build results: 5m53s clean, 718 tests passed
- Fix line count ~133K → ~103K (verified via wc -l)
- Add tokamak feature to OVERVIEW.md feature tables

Split monolithic `tokamak` feature into 3 independent features
(tokamak-jit, tokamak-debugger, tokamak-l2) with umbrella re-export.
Add pr-tokamak.yaml CI workflow for quality-gate and format checks.
Update snapsync action default image to tokamak-network/ethrex.
Document sync architecture, Hive test matrix, and success criteria.

Add structured benchmark infrastructure to tokamak-bench crate:
- timings.rs: reset(), raw_totals(), raw_counts() accessors
- tokamak-bench: types, runner, report, regression modules + CLI binary
- CI workflow: pr-tokamak-bench.yaml (bench PR vs base, post comparison)
- 11 unit tests covering regression detection, JSON roundtrip, reporting

Feature unification causes these modules to be compiled during L2
workspace clippy. Add targeted allows for arithmetic_side_effects,
as_conversions, expect_used, and unsafe_code lints.

Add the core JIT tiered compilation modules that were missing from
the branch: execution counter, code cache dispatch, types, and
module declaration. These provide the lightweight in-process
infrastructure gated behind the tokamak-jit feature flag.

- tokamak-jit: compiler, backend, adapter, validation, error modules
- JIT backend CI job with LLVM 18 in pr-tokamak.yaml
- jit_bench module in tokamak-bench for interpreter vs JIT comparison
- Phase 2 architecture documentation
- Updated HANDOFF with current status

Add Phase 3 JIT execution wiring so JIT-compiled bytecode actually
runs through the VM dispatch instead of only being compiled.

Key changes:
- JitBackend trait in dispatch.rs for dependency inversion (LEVM
  defines interface, tokamak-jit implements)
- LevmHost: revm Host v14.0 implementation backed by LEVM state
  (GeneralizedDatabase, Substate, Environment)
- Execution bridge: builds revm Interpreter, wraps state in LevmHost,
  transmutes CompiledCode to EvmCompilerFn, maps result to JitOutcome
- vm.rs wiring: try_jit_dispatch() && execute_jit() before interpreter
  loop, with fallback on failure
- register_jit_backend() for startup registration
- E2E tests: fibonacci JIT execution + JIT vs interpreter validation
  (behind revmc-backend feature, requires LLVM 21)

Close 7 gaps preventing production use of the JIT system:

- 4A: Propagate is_static from CallFrame to revm Interpreter
- 4B: Sync gas refunds after JIT execution, pass storage_original_values
  through JIT chain for correct SSTORE original vs present value
- 4C: Add LRU eviction to CodeCache (VecDeque + max_entries)
- 4D: Auto-compile when execution counter hits threshold, add compile()
  to JitBackend trait and backend() accessor to JitState
- 4E: Detect CALL/CREATE/DELEGATECALL/STATICCALL opcodes in analyzer,
  skip JIT compilation for contracts with external calls
- 4F: Skip JIT when tracer is active, add JitMetrics with atomic
  counters, log fallback events via eprintln

…compilation, and validation

Phase 5 addresses three remaining JIT gaps:

5A — Multi-fork support: Cache key changed from H256 to (H256, Fork) so the
same bytecode compiled at different forks gets separate cache entries.
fork_to_spec_id() adapter added. Hardcoded SpecId::CANCUN removed from
compiler, execution, and host — all now use the environment's fork.

5B — Background async compilation: New CompilerThread with std::sync::mpsc
channel and a single background thread. On threshold hit, vm.rs tries
request_compilation() first (non-blocking); falls back to synchronous
compile if no thread is registered. register_jit_backend() now also
starts the background compiler thread.

5C — Validation mode wiring: JitConfig.max_validation_runs (default 3)
gates logging to first N executions per (hash, fork). JitState tracks
validation_counts and logs [JIT-VALIDATE] with gas_used and output_len
for offline comparison. Full dual-execution deferred to Phase 6.

M1: CompilerThread now implements Drop — drops sender to signal
    shutdown, then joins the background thread. Panics are caught
    and logged (no silent swallowing). Fields changed to Option
    for take-on-drop pattern.

M2: SELFDESTRUCT (0xFF) added to has_external_calls detection in
    analyzer.rs. Bytecodes containing SELFDESTRUCT are now skipped
    by the JIT compiler, preventing the incomplete Host::selfdestruct
    (missing balance transfer) from being exercised.

M3: Negative gas refund cast fixed in execution.rs. Previously
    `refunded as u64` would wrap negative i64 (EIP-3529) to a huge
    u64. Now uses `u64::try_from(refunded)` — negative values are
    silently ignored (already reflected in gas remaining).

M4: Documented fork assumption in counter.rs and vm.rs. Counter is
    keyed by bytecode hash only (not fork). Safe because forks don't
    change during a node's runtime; cache miss on new fork falls back
    to interpreter.

Add compare_jit() for detecting JIT speedup regressions between PR and
base branch (20% threshold). New JitCompare CLI subcommand, JIT
regression report types, and markdown output.

Add 3 CI jobs to pr-tokamak-bench.yaml: jit-bench-pr, jit-bench-main,
compare-jit-results with PR comment integration. LLVM 21 jobs use
continue-on-error until C-2 provisioning is complete.

10 new tests covering regression/improvement detection, edge cases
(missing scenario, None speedup, multi-scenario), and report output.

Update roadmap, status, and execution order. Phase 9 now ~50% complete.
Feature lambdaclass#10 Continuous Benchmarking advances to ~50%. Next: C-2 (LLVM
provisioning) and B-3 (EIP-7928 BAL recording).

Extract inline LLVM 21 installation into .github/actions/install-llvm/
composite action. Includes llvm-dev and libpolly-dev packages (fixes
Polly linking issue). Update pr-tokamak.yaml and pr-tokamak-bench.yaml
to use the new action, removing continue-on-error workaround.

…hs (B-3)

Implement Block Access List (BAL) recording in the JIT execution path
so that storage reads/writes are tracked identically to the interpreter.

- Record storage reads in sload_skip_cold_load() via bal_recorder
- Record implicit reads + conditional writes in sstore_skip_cold_load()
- Remove 4 TODO comments, replace with architectural notes
- Add 5 differential tests (JIT vs interpreter BAL comparison)
- Apply cargo fmt to tokamak-jit crate

…fallback (D-2)

Add explicit handling for oversized bytecodes (> 24576 bytes, EIP-170)
that cannot be JIT-compiled by revmc/LLVM. Previously, compilation
would fail silently with repeated cache lookups on every call frame.

Changes:
- Add negative cache (oversized_hashes FxHashSet) to JitState for
  O(1) skip of known-oversized bytecodes
- Add early size gate in VM dispatch at compilation threshold,
  preventing compilation attempts before they reach the backend
- Add belt-and-suspenders size check in background compiler thread
- Return interpreter-only benchmark results instead of silently
  dropping oversized scenarios (Push/MstoreBench/SstoreBench)
- 4 unit tests for oversized cache + 3 integration tests (revmc-gated)

…:is_bytecode_oversized()

Replace 4 inline `len > max_bytecode_size` comparisons with a single
method on JitConfig. Also update STATUS.md with D-2 completion details.

… pipeline (D-3)

Same-length PUSH+PUSH+OP → single wider PUSH replacement preserving
bytecode offsets (JUMP targets, basic blocks unchanged). Supports
ADD, SUB, MUL, AND, OR, XOR with SUB wrapping edge case handling.

- optimizer.rs: detect_patterns() scan + optimize() constant folding
- Pipeline integration between analyze_bytecode() and compile()
- 37 unit tests + 5 integration tests (42 total for D-3)

… sync verification

- Replace hardcoded lambdaclass/ethrex with ${GITHUB_REPOSITORY} in
  snapsync-run action so assertoor can fetch the syncing-check config
  from the correct fork (tokamak-network/ethrex)
- Change default build_profile from release to release-with-debug-assertions
  so state trie validation (debug_assert!) fires during sync verification

ethrex-sync self-hosted runner is not available on tokamak-network fork.
Use GitHub-hosted ubuntu-latest runner with Kurtosis installed via apt.
Remove engine-restart job (only needed for persistent self-hosted runner).

Hoodi snap sync on GitHub-hosted runner did not complete within 1h.
Both EL and CL remained unsynced for the entire duration (run #22395022810).

…etion

- Overall completion 45-50% → 55-60%
- JIT feature 75% → 80%, test count 58 → 104
- Remove "Opcode fusion, constant folding" from Remaining
- Add D-3 to Recently Completed (Phase D) section
- Update codebase line counts (8,743 → 9,657)
- Update In Progress: next is E-1 or A-2

…level recording (E-1)

LEVM hook infrastructure:
- OpcodeRecorder trait in debugger_hook.rs (feature-gated tokamak-debugger)
- Stack::peek() for non-destructive stack inspection
- Per-opcode callback in interpreter_loop (before advance_pc)

tokamak-debugger crate:
- DebugRecorder captures opcode, PC, gas, depth, stack top-N, memory size
- ReplayEngine with record(), forward(), backward(), goto() navigation
- ReplayTrace + StepRecord + ReplayConfig data types
- DebuggerError with VM and StepOutOfRange variants

14 tests: basic replay (4), navigation (5), gas tracking (3), nested calls (2)

… debugger (E-2)

Add a REPL-based debugger CLI on top of the E-1 replay engine, gated
behind the `cli` feature flag. Supports 13 commands: step, step-back,
continue, reverse-continue, break, delete, goto, info, stack, list,
breakpoints, help, quit.

New files:
- src/bin/debugger.rs — binary entry point (clap)
- src/cli/mod.rs — Args, InputMode, run(), DB setup
- src/cli/commands.rs — Command enum, parse(), execute()
- src/cli/formatter.rs — step/info/stack/breakpoints display
- src/cli/repl.rs — rustyline REPL loop
- src/tests/cli_tests.rs — 27 tests (parsing, formatter, execution)

Usage: cargo run -p tokamak-debugger --features cli -- bytecode --code 600360040100

Add `debug_timeTravel` RPC method that replays a transaction at opcode
granularity and returns a window of execution steps for time-travel
debugging over JSON-RPC.

- Extract `prepare_state_for_tx()` from `trace_transaction_calls()` in
  blockchain/tracing.rs for reuse by the debugger endpoint
- Add `Evm::setup_env_for_tx()` wrapper in vm/tracing.rs
- Change `LEVM::setup_env` visibility to pub(crate)
- Add serde Serialize derives to StepRecord, ReplayTrace, ReplayConfig
- Add `opcode_name()` method to StepRecord
- Feature-gate behind `tokamak-debugger` in ethrex-rpc
- 10 tests: 6 RPC handler + 4 serde round-trip

Add `cross-client` CLI subcommand that compares ethrex execution
performance against Geth and Reth using eth_call with state overrides.

- ethrex runs in-process (reuses existing runner), external clients
  via JSON-RPC eth_call with bytecode injected at state override address
- New cross_client module: types.rs, runner.rs, report.rs
- Markdown report with ethrex as 1.00x baseline, ratio per client
- Feature-gated behind `cross-client` (reqwest, tokio, url deps)
- 18 tests covering serialization, parsing, reporting

…on (F-4)

Add cargo-fuzz harnesses, property-based tests, and unsafe code audit
documentation for the JIT compiler.

- 3 fuzz targets: analyzer, optimizer, differential (standalone crate)
- 4 proptest property tests: never-panics, bounds, length-preserving,
  convergence (optimizer is NOT single-pass idempotent)
- SAFETY_AUDIT.md cataloging all 9 unsafe blocks with risk assessment
- Update ROADMAP and STATUS docs to reflect E-3, F-1, F-4 completion

- Rewrite fuzz_differential.rs for actual JIT vs interpreter comparison:
  generate random EVM bytecode, execute on both paths, compare status/gas/output
- Add tokamak-jit as optional dep, wire revmc-backend feature properly
- Fallback to interpreter determinism check when LLVM unavailable
- Add DASHBOARD-SPEC.md for F-2 public dashboard (clients.tokamak.network):
  no-backend architecture, 6 pages, 4-phase implementation plan

Astro + React islands + Recharts + Tailwind static site at dashboard/.
Fetches benchmark JSON from CI artifacts and displays:
- Landing page with metric cards and benchmark table
- Historical trends page with scenario selector and CI error bands

Includes:
- 16 TypeScript interfaces mirroring Rust bench types
- Zod schemas with commit hash, timestamp, and path validation
- Path traversal protection in fetch layer
- 11 React components (MetricCard, StatusBadge, BenchTable, TrendChart, etc.)
- rebuild-index.py script for CI data pipeline
- publish-dashboard CI job in pr-tokamak-bench.yaml
- 62 JS/TS tests (Vitest) + 9 Python tests (unittest)

…nd STATUS

… flag (F-3)

- TokamakFeeConfig + JitPolicy types (crates/common)
- TokamakL2Hook wrapping L2Hook via composition (crates/vm/levm)
- VMType::TokamakL2 variant + hook dispatch + Evm constructors
- BlockchainType::TokamakL2 + 5 match arm updates (blockchain.rs)
- --tokamak-l2 CLI flag with env var support
- Feature propagation across 6 Cargo.toml files
- P256Verify precompile extended via is_l2_type() helper
- 7 unit tests (4 fee config serde + 3 hook)